what about an idToken? idTokens are useful as they contain claims that are good to display like usernames/email/etc.

So unless I'm mistaken, the runtime wouldn't have any actual use for it; all it needs as a response from the host is the access token to be forwarded back to the MCP server for access... In fact, I'm about to remove the refreshToken from here, since as discussed in yesterday's meeting, refresh would be the host's responsibility, and so the runtime has no use for that.

But let me know if I have the wrong mental model here! Plus we can always add it later.

Are these necessarily tied together?

I'm thinking back to permission requests and tool invocation requests. Initially the only way you could handle them was to provide a handler that the SDK would invoke, but that was prohibitive, especially with regards to needing to be able to suspend the runtime and later resume it (possibly on a different machine) and supply the result of the operation in order to keep going. We made it so that providing the callback was optional; if you don't supply it, you're on your own for handling the events and calling the runtime rpc method to supply the results.

Is there a correlary here?

Yeah, at least at the moment, register interest in the callback is necessary since the runtime has two MCP OAuth flows - the new one being introduced here and the in-process one currently used by the CLI; I'm working on a PR to switch the CLI to use the new SDK flow - as part of the CLI-over-SDK effort - but for now the interest registration is required in order for the runtime to know which path to take.

Regardless, even after we remove the CLI flow, I'm not sure how the "you're on your own" approach would work here MCP OAuth... The LLM can request a tool call at an arbitrary time, which could trigger an "oauth_required" request, which must be satisfied by the host; if this doesn't happen, the tool call can't proceed, and the turn is stuck. So I think it means the host must be informed (and it must respond in a timely manner)... I think that this oauth flow must indeed be rewired upon resume (even on a different machine), but it doesn't change the fact that an OAuth request can happen at any point, and the host must be able to handle it...

In other words, I think that any SDK host that potentially needs to support OAuth-authorizing MCP servers must register this callback, and if such a request is emitted without that callback being registered, I'm not sure what choice we have besides a fail-fast error... But I might have an incorrect mental model here - let me know how you see this.

To make sure I've understood correctly, all the SDK ends up doing is listening for a particular event, invoking the user's callback, and calling the exposed RPC method to supply the result, right? So SDK consumer could do the same thing without providing a callback: they could listen for the same event, do whatever they want in response (whatever they would have supplied in the callback), and then call that same RPC method, right?

The PR is using a callback being set as an indication that the client is handling oauth, but if the above is true, then those needn't be 1:1... supplying a callback could imply it, but not supplying a callback doesn't mean the client can't also handle it. My question is really: should there be a separate knob for opting-in to handling oauth beyond just supplying a callback.

It's fine if the answer is "not right now, we could always add one in the future if supplying a callback is problematic for some reason".

EDIT: Maybe read my comment below, I think I understood better what you were asking

Here's how the flow works:

1. The runtime makes an MCP call, and receives a 401/403 HTTP error, signifying that a (new) OAuth access token is required. Crucially, the runtime is the one seeing this - the hosting application (or client) has no idea it's happening.
2. In the new host-delegating flow (when "interest is registered"), the runtime records the pending OAuth request and then invokes the callback in the hosting application, passing it various information from the 401 response (e.g. WWW-Authenticate header contents).
3. The hosting application does whatever is needed in order to obtain the access token (user browser flow, or possibly just a refresh cycle).
4. The hosting application then calls an API back into the SDK (handlePendingRequest)
5. Back in the runtime, we correlate the request ID given to handlePendingRequest with the recorded OAuth request from step 2, and then redoes the MCP request with the new auth token received from the host.

IIUC you're asking whether it makes sense to have a host opt into host-delegated OAuth without registering a callback. In that case, I can't see what would happen when the runtime receives a 401/403 HTTP error which is the trigger for OAuth - how would the host application be made aware that OAuth needs to happen? Like are you thinking of some sort of polling mechanism where the host application would periodically check if there are any pending OAuth requests? I guess that's theoretically possible, but would at the very least mean lots of latency no?

Are you asking because reinstating host callbacks with the runtime after resume is problematic? I looked at this and it seems that we have several other callbacks which IIRC are should also be reinstated after resume - but I could be wrong.

Happy to do a quick call tomorrow to discuss all this!

OK, I reread everything and I think I understand your concern... You're saying that in the SDK implementation here (not the runtime), we expose a single callback which must return the token; this would prevents e.g. an implementation that persists the various parameters to disk, and then some other processes loads those and calls handlePendingRequest with the token. In other words, this is less about separating the opt-in from the callback, it's more to have a more low-level split interaction where there's the callback invoked by the runtime doesn't have to return an access token "immediately", and the host application later invokes handlePendingRequest manually.

I can see that... And that's exactly how the low-level RPC API is actually structured (oauth_required is the low-level callback that returns nothing). If so, then I think all this should be achievable with the low-level APIs today:

await session.Rpc.EventLog.RegisterInterestAsync("mcp.oauth_required");

using var sub = session.On<McpOauthRequiredEvent>(evt =>
{
    // Persist requestId + auth params.
    // Do not return token; this is just an event callback.
});

// Later / elsewhere:
await session.Rpc.Mcp.Oauth.HandlePendingRequestAsync(requestId, tokenResult);

There may be some issues around registering interest (and the callback) early enough during resume so as to avoid any race conditions... Also, specifically for the multiple process scenario (one process receives oauth_required, persists, another process actually completes with the access token), the runtime itself needs to remember/correlate the pending OAuth requests, and that's in-memory only; so a true resume will have lost that (assuming the runtime is in the same process as the host application).

tl;dr I think we have a nice high-level convenience callback for the common scenario (register a single async callback that returns the access token). In principle, users can still drop down to low-level RPC APIs to do the advanced (cross-process) thing, but it's likely we have some gaps around this - but they go beyond simple API shape here in the SDK, and we should probably think/design that separately (the main question is whether the high-level API as-is seems OK even if the advanced scenario isn't there yet).

Does this all make sense and correspond to what you're asking?

Cross-SDK consistency note: Unlike the other Rust handler data structs in this file — PermissionRequestData and ElicitationRequest neither of which include a request_id field — McpAuthRequest exposes pub request_id: RequestId here.

Because McpAuthHandler::handle already passes request_id as a dedicated top-level parameter (matching the PermissionHandler / ElicitationHandler pattern), this field is redundant: the same value is accessible via both request_id and request.request_id.

In every other SDK, requestId/request_id lives only inside the request object (it is never a separate parameter):

• Node.js/Python: handler(request, { sessionId }) — request.requestId
• Go: handler(request MCPAuthRequest, invocation MCPAuthInvocation) — request.RequestID
• .NET: handler(McpAuthContext) — context.RequestId (single unified object)
• Java: handle(McpAuthRequest request, McpAuthInvocation invocation) — request.requestId()

Consider removing request_id from McpAuthRequest to stay consistent with the Rust SDK's own PermissionRequestData/ElicitationRequest types and with the other language SDKs. If you'd like the struct to be self-contained (e.g. for storing the request after the handler returns), it's worth noting this departure in a doc comment.